MODULE = PlPN          PACKAGE = PlPN::TextEditorEventSink

#
# this package doesn't used the standard XS/C++ interface
# because the object is a boost shared_ptr, not a real pointer
#

#
# Pod::Html is kind of brain-dead:
#
# Place Z<> between function names and parentheses, otherwise Pod::Html
# assumes you meant to put C<...> around it
#
# Put explicit text in all links L<use my text, stupid|some::perl::module>,
# otherwise Pod::Html assumes you want "the X manpage". (Does not apply to
# relative links withing this file.)
#
# It also assumes you want a link if you have C<...> with text matching a
# potential link target. The only way I've found around that is to split it
# up into multiple pieces: C<wo>C<rd>. Looks correct in the resulting HTML,
# but it's ugly to have <code>wo</code><code>rd</code> in the source, and I
# shouldn't have to do it.
#

=head1 NAME

PlPN::TextEditorEventSink - The document event sink

=head1 SYNOPSIS

	{
		package MyTextEditorEventSinkWithUniqueClassName;
		use PlPN;
		our @ISA = qw(PlPN::TextEditorEventSink);
		
		sub OnCharAdded {
			# do something
		}
		
		# etc.
	} # scope ends; return to original package
	
	use PlPN qw(PN);
	
	my $editorsink = new MyTextEditorEventSinkWithUniqueClassName;
	$some_doc->AddEventSink($editorsink);
	
	# etc.

=head1 DESCRIPTION

Catches text editor events (well, currently the single text editor event)
from Programmer's Notepad documents.

The default constructor simply blesses an empty hashref into the class.

The default event does nothing; it exists so that derived classes can omit
it without causing Perl to crash when C++ code tries to call the event. (Of
course, it would be rather stupid to implement this kind of event sink and
not implement its only event, but this behavior allows for additional events
later.

The document object is always passed as the first parameter of the event;
this allows the same text editor sink to be used with multiple documents.

=head1 EVENT

=over
		
=item OnCharAdded($doc, $char)

See L<PlPN::RegisterEvent|PlPN/RegisterEvent> for a description of this
event.

=back

=head1 COPYRIGHT and LICENCE

Copyright (c) 2012 Sean Healy. All rights reserved.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

=cut

SV*
new(CLASS)
		const char* CLASS;
	CODE:
		HV* hv = newHV();
		RETVAL = newRV_noinc((SV*)hv);
		sv_bless(
			RETVAL,					/* reference to be blessed */
			gv_stashpv(CLASS, 1)	/* stash to bless it into */
		);
	OUTPUT:
		RETVAL

# we shouldn't need a DESTROY

void
OnCharAdded(...)
	CODE:
		// default implementation so we don't croak for lack of a method

